home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / kernel / timer / timer.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-12-19  |  9.7 KB  |  289 lines
  1. /*
  2.  * timer.h --
  3.  *
  4.  *     External definitions for the clock timer routines.
  5.  *
  6.  * Copyright 1985, 1988 Regents of the University of California
  7.  * Permission to use, copy, modify, and distribute this
  8.  * software and its documentation for any purpose and without
  9.  * fee is hereby granted, provided that the above copyright
  10.  * notice appear in all copies.  The University of California
  11.  * makes no representations about the suitability of this
  12.  * software for any purpose.  It is provided "as is" without
  13.  * express or implied warranty.
  14.  *
  15.  * rcsid: $Header: /cdrom/src/kernel/Cvsroot/kernel/timer/timer.h,v 9.8 92/06/01 14:48:03 kupfer Exp $ SPRITE (Berkeley) 
  16.  */
  17.  
  18. #ifndef _TIMER
  19. #define _TIMER
  20.  
  21. #include <list.h>
  22.  
  23. #ifdef KERNEL
  24. #include <spriteTime.h>
  25. #include <timerTick.h>
  26. #include <timerMach.h>
  27. #include <syncLock.h>
  28. #else
  29. #include <spriteTime.h>
  30. #include <kernel/timerTick.h>
  31. #include <kernel/timerMach.h>
  32. #include <kernel/syncLock.h>
  33. #endif
  34.  
  35.  
  36. /*
  37.  * Interval Timers:
  38.  *  The systems should provide two interval timers capable of interrupting 
  39.  *  the CPU after a specified interval, calling the correct routine, and
  40.  *  reseting themselves to interrupt again. 
  41.  * The timers are:
  42.  *  TIMER_CALLBACK_TIMER is the timer used to determine when
  43.  *      the first routine on the timer queue should be called.
  44.  *  TIMER_PROFILE_TIMER is the timer used to determine when
  45.  *      the profile routine should be called.
  46.  */
  47.  
  48. #define TIMER_CALLBACK_TIMER    2
  49. #define    TIMER_CALLBACK_ROUTINE    Timer_CallBack
  50.  
  51. #define TIMER_PROFILE_TIMER    3
  52. #define    TIMER_PROFILE_ROUTINE    Prof_CollectInfo
  53.  
  54. /*
  55.  * timerTick.h should define the following types/structures/routine/macros for 
  56.  * the desired architecture:
  57.  *
  58.  *   typedef    Timer_Ticks -    The typedef of the object that can 
  59.  *                hold the value of the machine's timers.
  60.  *                This is should be in a format that
  61.  *                can be quickly generated from the 
  62.  *                timer values provided by the hardware.
  63.  *                The idea here is to leave the timer
  64.  *                values in these "natural" units to
  65.  *                avoid expensive conversions on the
  66.  *                frequent timer interrupts.
  67.  *
  68.  *    Tick arithmetic and conversion routines. May be macros.
  69.  *----------------------------------------------------------------------
  70.  *
  71.  *  Timer_AddTicks --
  72.  *
  73.  *     Adds two tick values together.
  74.  *
  75.  *  void
  76.  *  Timer_AddTicks(a, b, resultPtr)
  77.  *    Timer_Ticks        a;        Addend 1 
  78.  *    Timer_Ticks        b;        Addend 2 
  79.  *    Timer_Ticks        *resultPtr;    Sum 
  80.  *----------------------------------------------------------------------
  81.  *
  82.  *  Timer_SubtractTicks --
  83.  *
  84.  *     Subtracts the second parameter from the first parameter. 
  85.  *    The second parameter must be less than the first, otherwise 
  86.  *    a zero tick value is returned.
  87.  *
  88.  *  void
  89.  *  Timer_SubtractTicks(a, b, resultPtr)
  90.  *    Timer_Ticks        a;        Minuhend 
  91.  *    Timer_Ticks        b;        Subtrahend 
  92.  *    Timer_Ticks        *resultPtr;    Difference 
  93.  *    
  94.  *----------------------------------------------------------------------
  95.  *
  96.  *  Timer_AddIntervalToTicks --
  97.  *
  98.  *     Adds an interval (32-bit value) to an absolute time (64-bit value).
  99.  *
  100.  *    void
  101.  *    Timer_AddIntervalToTicks(absolute, interval, resultPtr)
  102.  *    Timer_Ticks        absolute;    Addend 1 
  103.  *    unsigned int         interval;    Addend 2
  104.  *    Timer_Ticks        *resultPtr;    Sum 
  105.  *----------------------------------------------------------------------
  106.  *
  107.  *  Timer_GetCurrentTicks --
  108.  *
  109.  *      Computes the number of ticks since the system was booted.
  110.  *
  111.  *    void
  112.  *    Timer_GetCurrentTicks(ticksPtr)
  113.  *    Timer_Ticks    *ticksPtr;    Buffer to place current time. 
  114.  *----------------------------------------------------------------------
  115.  *
  116.  *  Timer_TicksToTime --
  117.  *
  118.  *      Converts a Timer_Ticks value into a Time value.
  119.  *    void
  120.  *    Timer_TicksToTime(tick, timePtr)
  121.  *    Timer_Ticks    tick;    Value to be converted. 
  122.  *    Time    *timePtr;    Buffer to hold converted value. 
  123.  *----------------------------------------------------------------------
  124.  *
  125.  *  Timer_TimeToTicks --
  126.  *
  127.  *      Converts a Time value into a Timer_Ticks value.
  128.  *   void
  129.  *    Timer_TimeToTicks(time, ticksPtr)
  130.  *    Time    time;                Value to be converted. 
  131.  *    Timer_Ticks    *ticksPtr;    Buffer to hold converted value.
  132.  *----------------------------------------------------------------------
  133.  *
  134.  * TimerTicksInit --
  135.  *
  136.  *    Initializes the various tick and interval values.
  137.  *
  138.  * void
  139.  * TimerTicksInit()
  140.  *----------------------------------------------------------------------
  141.  * Tick Comparisons --
  142.  *
  143.  *    Timer_TickLT(tick1,tick2):    tick1  <   tick2
  144.  *    Timer_TickLE(tick1,tick2):    tick1  <=  tick2
  145.  *    Timer_TickEQ(tick1,tick2):    tick1  ==  tick2
  146.  *    Timer_TickGE(tick1,tick2):    tick1  >=  tick2
  147.  *    Timer_TickGT(tick1,tick2):    tick1  >   tick2
  148.  *
  149.  *----------------------------------------------------------------------
  150.  * Additionally, timerTick.h should provide the following frequently used
  151.  * tick and intervals values. These values should be initialized by the 
  152.  * machine dependent routine TimerTicksInit().  
  153.  * 
  154.  * extern unsigned int     timer_IntZeroSeconds; - Zero seconds worth of ticks.
  155.  * extern unsigned int     timer_IntOneMillisecond; - One milliseconds of ticks.  
  156.  * extern unsigned int     timer_IntOneSecond; - One second of ticks.
  157.  * extern unsigned int     timer_IntOneMinute; - One minute of ticks.
  158.  * extern unsigned int     timer_IntOneHour;  - One hour of ticks.
  159.  * extern Timer_Ticks    timer_TicksZeroSeconds; - Zero seconds worth of ticks.
  160.  * extern Time         timer_MaxIntervalTime; 
  161.  *      - Maximum time for a unsigned 32-bit interger worth of ticks. This
  162.  * is the longest possible interval value.
  163.  */
  164.  
  165.  
  166.  /* DATA STRUCTURES: */
  167.  
  168.  
  169. /*
  170.  *  TimerQueueElement defines the structure to store info about a
  171.  *  routine so it can be called at its scheduled time.
  172.  *
  173.  *  Only three fields need to be filled in by the client before passing 
  174.  *  the element's address to Timer_ScheduleRoutine:
  175.  *    a) The address of the routine,
  176.  *    b) The time when the routine should be called. 
  177.  *       If the time value is an "absolute" time and not a time 
  178.  *       relative to the current time, use the time field.
  179.  *       If the time value is relative to the current time, use 
  180.  *       the interval field.
  181.  *    c) Client-specific data to be passed to the routine when it is 
  182.  *       called.
  183.  *
  184.  *  Since the client controls the storage of the timer queue element, it
  185.  *  could modify fields of the structure while it is on the timer queue.
  186.  *  Once the element is scheduled, it must be treated as read-only!!
  187.  *  Only when the scheduled routine is called or descheduled can the element 
  188.  *  be modified by the client.
  189.  *
  190.  *  Note:  Do not access any part of the structure that is 
  191.  *         labeled "private". These fields can be accessed only by 
  192.  *       the Timer module routines.
  193.  *
  194.  *       Public fields marked "readonly" must not be modified by 
  195.  *       the client.
  196.  *
  197.  */
  198.  
  199.  
  200. typedef struct {
  201.     List_Links    links;        /* private: */
  202.  
  203.     void    (*routine) _ARGS_((Timer_Ticks timeTicks, 
  204.                   ClientData  clientData));    
  205.                     /* public:  address of the routine */
  206.     Timer_Ticks    time;        /* public:  time when the routine should be
  207.                  *         called. interval field is ignored*/ 
  208.     ClientData    clientData;    /* public:  data passed to the routine when
  209.                  *        called. */
  210.  
  211.     Boolean    processed;    /* public, readonly:  TRUE if routine has
  212.                  *         been called (at its scheduled time),
  213.                  *        FALSE if not called yet. */
  214.     unsigned int interval;    /* public:  interval relative from now when 
  215.                  *         the routine should be called.
  216.                  *        The time field becomes private. */
  217. } Timer_QueueElement;
  218.  
  219. /*
  220.  *  The statistics counts used by the dump routines.
  221.  */
  222.  
  223. typedef struct {
  224.     int        callback;    /* count of callback timer interrupts */
  225.     int        profile;    /* count of profile timer interrupts */
  226.     int        spurious;    /* count of spurious timer interrupts */
  227.     int        schedule;    /* count of Timer_ScheduleRoutine calls */
  228.     int        resched;    /* count of Timer_RescheduleRoutine calls */
  229.     int        desched;    /* count of Timer_DescheduleRoutine calls */
  230. } Timer_Statistics;
  231.  
  232. extern Timer_Statistics    timer_Statistics;
  233. extern Time        timer_UniversalApprox;
  234. extern Sync_Semaphore     timer_ClockMutex;
  235.  
  236. #ifdef ADJTIME
  237. extern Time        timer_AdjustDelta;
  238. extern unsigned        timer_TickAdjust;
  239. extern int        timer_TickDelta;
  240. #endif
  241.  
  242. /*
  243.  * Used to get the current seconds value of the universal time. This is
  244.  * the quickest way to get a timestamp and is used in the filesystem.
  245.  */
  246.  
  247. #define Timer_GetUniversalTimeInSeconds()  (timer_UniversalApprox.seconds)
  248.  
  249. extern void Timer_Init _ARGS_((void));
  250. extern void Timer_ScheduleRoutine _ARGS_((register 
  251.             Timer_QueueElement *newElementPtr, Boolean interval));
  252. extern Boolean Timer_DescheduleRoutine _ARGS_((register 
  253.             Timer_QueueElement *elementPtr));
  254. extern void Timer_GetTimeOfDay _ARGS_((Time *timePtr, int *timerLocalOffsetPtr,
  255.             Boolean *DSTPtr));
  256. extern void Timer_GetRealTimeOfDay _ARGS_((Time *timePtr, 
  257.             int *timerLocalOffsetPtr, Boolean *DSTPtr));
  258. extern void Timer_GetRealTimeFromTicks _ARGS_((Timer_Ticks ticks, 
  259.             Time *timePtr, int *timerLocalOffsetPtr, 
  260.             Boolean *DSTPtr));
  261. extern Boolean Timer_OkToWhine _ARGS_((char *msg));
  262. extern void Timer_SetTimeOfDay _ARGS_((Time newUniversal, int newLocalOffset, 
  263.             Boolean newDSTAllowed));
  264. #ifdef ADJTIME
  265. extern ReturnStatus Timer_AdjustTime _ARGS_((Time *newDelta, Time *oldDelta));
  266. extern ReturnStatus Timer_GetParams _ARGS_((unsigned *tickadj));
  267. extern ReturnStatus Timer_SetParams _ARGS_((unsigned tickadj));
  268. #endif
  269.  
  270.  
  271. /*
  272.  * Exported procedures. The arguments and function of this interface are be
  273.  * found in any of the machine dependent implementations.
  274.  */
  275.  
  276. extern void Timer_TimerInit _ARGS_((int timer));
  277. extern void Timer_TimerStart _ARGS_((int timer));
  278. extern void Timer_TimerInactivate _ARGS_((int timer));
  279.  
  280.  
  281. /*
  282.  * Used by the dump routines in the utils module for debugging.
  283.  */
  284. extern void Timer_TimerGetInfo _ARGS_((ClientData data));
  285. extern void Timer_DumpQueue _ARGS_((ClientData data));
  286. extern void Timer_DumpStats _ARGS_((ClientData arg));
  287.  
  288. #endif /* _TIMER */
  289.